Search
  1. Home
  2. Documentation
  3. OneSpan Sign
  4. Guides
  5. Admin Guides
  6. Bulk Sending

Bulk Sending

Last modified: 2024-11-01

Bulk Sending

The Bulk Send feature enables users to create and distribute multiple transactions with minimum effort by using:

  • An eligible template, which will be used to create the transactions. A template is "eligible" if it has:
    • At least one document other than the Consent Agreement
    • At least one placeholder Role
    • At least one Signature Field (not necessarily for the placeholder Role)
  • A CSV file, which contains signer information for all placeholder Roles

This rest of this section discusses:

Supported Languages

If the list of supported languages has been limited note the following:

  • Users will not be allowed to generate new Bulk Send transactions for templates having an unsupported language. 

  • The Bulk Send option will be hidden from the sender UI (on the Templates list page as well as within the Template Edit page).

  • Attempting to trigger a Bulk Send from the API for a template with an unsupported language will throw an error.

  • When creating a transaction or template from the UI, if you select a bulk send-able template from the drop-down that now has an unsupported language, the Bulk Send Upload option will be there as the new transaction or template language will be automatically reset to the default signing language.

  • Already generated Bulk Send transactions with a now unsupported language will still be processed, but will throw an error because of the now unsupported language.

File Sizes and Processing Capacity

Note that bulk sending is subject to the following limitations:

  • The maximum file size is 8 MB.

  • A maximum of approximately 3000 transactions are processed per hour.

As such, for a very large bulk send we recommend that you break your request into smaller batches of 1000 lines per hour. Doing this will help avoid blocking the transaction queue for other users.

If possible, initiate your bulk send over the weekend. This will lessen the impact on other users, and help process your transactions faster.

Initiating a Bulk Send

Prerequisites

  • The Bulk Send feature must be enabled on your account.
  • An eligible template and suitable CSV file have been created.

    • The CSV file must specify the ID of the signing method. That ID is case-sensitive. For the method Signing with a Certificate, that ID is "personalCertificateSigning".

To initiate a Bulk Send:

  1. Click the Templates menu option. The Templates page appears.
  2. Click the name of an eligible template. Its page appears.
  3. In the Template details section of that page, click the Bulk send transactions icon .
    Your system Explorer opens.
  4. Use your system Explorer to select a suitable CSV file. OneSpan Sign will validate its file format. If the format is valid, the Bulk Send process will begin.

    5. When initiating a Bulk Send using SMS, the phone numbers must follow the E.164 format. For example, +44 7923 123456 in Europe, and +1 247 123 4567 in North America.

CSV Header Format

This section describes the CSV header format for:

One Placeholder

For transactions with one placeholder Role, the header row in a CSV file must have the following format:

{PlaceholderRoleName},FIRST_NAME,LAST_NAME,EMAIL,AUTH_TYPE,AUTH_PROMPT,AUTH_CHALLENGE,SIGNER_VERIFICATION,FieldId1,FieldId2

Note that:

  • The string {PlaceholderRoleName} will not appear in the file. Instead, it will be the name of a placeholder Role. Similarly, the strings FieldId1 and FieldId2 will not appear in the file. Instead, they will be field ID names.
  • {PlaceholderRoleName}, FIRST_NAME, LAST_NAME, and EMAIL are required fields. All others are optional.
  • The AUTH_TYPE, AUTH_PROMPT, and AUTH_CHALLENGE parameters are treated by OneSpan Sign as a single AUTH field.
  • A FieldId is the ID of a field that belongs to a placeholder Role. It can be used to automatically populate that field in your documents. The header row can have as many of those fields as you need.
  • The rows under the header row provide values for the parameters in the header row. There is one such row for each transaction.
  • If you want to specify a method of External Signer Verification (SIGNER_VERIFICATION) such as PCC or DIGIPASS, please contact our Support Team.

Multiple Placeholders

If your transactions contain more than one placeholder Role, you must append a set of header fields for each additional role. All required fields must be present for each placeholder Role. For example, a header containing just the required fields for two placeholder Roles could look like this:

Placeholder1,FIRST_NAME,LAST_NAME,EMAIL,Placeholder2,FIRST_NAME,LAST_NAME,EMAIL

The {PlaceholderRoleName} field always defines the start of a Role Block. Note that:

  • Each Role Block must contain all required fields.
  • Within a given Role Block, the order of the fields doesn't matter. Pay close attention to the wording of the previous sentence because: (1) the AUTH field has three columns; (2) the FieldId field may have multiple parameters and therefore multiple columns.

Thus the following format is valid, even though the field order differs between its two Role Blocks:

Placeholder1,EMAIL,LAST_NAME,FIRST_NAME,Placeholder2,FIRST_NAME,EMAIL,LAST_NAME

Sample CSV File

Here is a sample CSV file for a transaction with two signers:

Signer1,FIRST_NAME,LAST_NAME,EMAIL,AUTH_TYPE,AUTH_PROMPT,AUTH_CHALLENGE,AUTH_PROMPT,AUTH_CHALLENGE,SIGNER_VERIFICATION,Signer2,FIRST_NAME,LAST_NAME,EMAIL,AUTH_TYPE,AUTH_PROMPT,AUTH_CHALLENGE,AUTH_PROMPT,AUTH_CHALLENGE,CUSTOMER_ID,SIGNER_VERIFICATION Signer1,David,Smith,[email protected],NONE,,,,,personalCertificateSigning,Signer2,Roger,Waters,[email protected],NONE,,,,133487, DIGIPASS

(1) AUTH_TYPE is assigned the value NONE for both signers; (2) 133487 is the CUSTOMER_ID.

CSV Files with Non-ASCII Characters

If the data you need to put in the CSV file contains non-ASCII characters (e.g., accented characters, Chinese characters), the CSV file should be saved with UNICODE UTF-8 encoding.

By default, Microsoft Excel saves files to CSV format using ANSI coding. The following procedure describes how to save Excel files to CSV format using UNICODE encoding.

To save an Excel file to CSV format using UNICODE UTF-8 encoding:

  1. Open the file in Microsoft Excel.
  2. From the top menu, click File > Save As, and browse to the desired directory.
  3. Select Save as type > CSV (Comma delimited) (*.csv).
  4. Beside the Save button, click Tools > Web Options....
  5. Click the Encoding tab.
  6. Click Save this document as > Unicode (UTF-8).
  7. In the Web Options window, click OK.
  8. Save the file.

Validation Process

OneSpan Sign validates the header row before validating any other row in a CSV file. If something is wrong with the header row, an error message is sent. If the header row is verified as valid, OneSpan Sign proceeds to validate the other rows.

The rest of this section discusses the validation of:

Header Row

OneSpan Sign verifies that in the CSV file's header row:

  • For each placeholder Role in the template, there is a Role Block that contains {PlaceholderRoleName}, FIRST_NAME, LAST_NAME, and EMAIL fields.
  • Every FieldId column corresponds to a field that exists for the associated Role.

Other Rows

OneSpan Sign verifies that for each Role Block in each row after the header row:

  • Values have been assigned to the FIRST_NAME, LAST_NAME, and EMAIL columns.
  • The value for each FieldId is valid. What "valid" means in this context depends on how you've configured the field (e.g., you may have assigned a maximum length to a text field). To better understand the possibilities, see Adding Fields to a Document.

AUTH Field

AUTH_TYPE, AUTH_PROMPT, and AUTH_CHALLENGE together constitute the "AUTH field" for a given Role Block.

The value assigned to AUTH_TYPE must be NONE, CHALLENGE, SSO, or SMS. The validation process for AUTH_PROMPT and AUTH_CHALLENGE depends on the value assigned to AUTH_TYPE, as explained in the rest of this section.

If AUTH_TYPE = NONE for a particular Role, OneSpan Sign does not try to validate AUTH_PROMPT or AUTH_CHALLENGE for that Role. That's because they're not used (see the sample CSV file above).

If AUTH_TYPE = CHALLENGE for a particular Role, OneSpan Sign verifies that for that Role:

  • At least one AUTH_PROMPT/AUTH_CHALLENGE pair has been specified.
  • There is a 1:1 mapping between prompts and challenges (i.e., for every prompt, there is a challenge — and vice versa).

OneSpan Sign reads prompt and challenge columns from left to right, which means that both of the following are valid ordering schemes:

AUTH_TYPE AUTH_PROMPT AUTH_CHALLENGE AUTH_PROMPT AUTH_CHALLENGE
CHALLENGE Question1 Answer1 Question2 Answer 2
AUTH_TYPE AUTH_PROMPT AUTH_PROMPT AUTH_CHALLENGE AUTH_CHALLENGE
CHALLENGE Question1 Question2 Answer1 Answer2

The above examples illustrate that all AUTH columns must appear in the order in which they're intended to be used. Here's another example which illustrates that concept: Answer2, Answer1, Question1, Question2 is not a valid order.

If AUTH_TYPE = SMS for a particular Role, OneSpan Sign verifies that for that Role there is at least one prompt. The verification process will examine only the first prompt, which should be used to specify the phone number to which an SMS message will be sent. The verification process ignores all other prompt and challenge parameters.

Bulk Send Scheduling

Bulk Send transactions are placed in a queue. Every 15 minutes, the queue is checked. If new Bulk Send jobs have arrived, they are processed in order until the queue is empty.

Video Tutorial

Was this information helpful?
X